~4Dgifts/toolbox/src/exampleCode/stereo/GL_5.2 README
==============================================================================
| README for StereoView Examples |
| 1/11/94 |
==============================================================================
This example code is derived from an older 4Dgifts directory that showed
how to use the original SGI StereoView implementation. In IRIX 5.2 and
later, SGI engineers enhanced the Xsgi X server to provide a more
sophisticated stereo implementation on some graphics devices. This
new implementation will be refered to as software-stereo-in-a-window or
SoftStereo. It has many of the characteristics of hardware-stereo-in-a-
window on Reality Engine but at a reduced resolution and price ;)
At the time these demos were put together it appeared likely that
SoftStereo will be supported under IRIX 5.2 on:
===>>> THIS LIST IS SUBJECT TO ADDITIONS OR DELETIONS WITHOUT NOTICE. <<<<====
XS
XZ
Elan
Extreme
Personal Iris GR1.2
XL (aka Indy graphics)
===>>> THIS LIST IS SUBJECT TO ADDITIONS OR DELETIONS WITHOUT NOTICE. <<<<====
STEREO API's
SoftStereo will use an API closely resembling the one use on Reality
Engine and in OpenGL. It uses only one window with two internal buffers
which may be refered to as STEREO_BUFFER_LEFT and STEREO_BUFFER_RIGHT.
The original SGI stereo implementation uses two windows which are normally
refered to as top and bottom.
SoftStereo offers a number of advantages over the old stereo implementation:
- X and Motif windows are displayed to both eyes without any extra
effort on the part of the application
- All windows are usable and there is no transparency or wrap around
between top and bottom buffers like the old stereo method
- The API, when fully implemented, will be easier to use and
consistent with stereo API's on Reality Engine and OpenGL.
Our apologies when you encounter example code that is hastily prepared
to use the new SoftStereo mode. Also apologies for the mixing of new
and old stereo API examples in one directory. It is hoped the examples
provided for SoftStereo should be usable in perpetuity although somewhat
more streamlined versions may be available in the future.
The next release will hopefully provide better coordinated examples of:
- Traditional stereo
- SoftStereo
- hardware-stereo-in-a-window
- OpenGL stereo
Promises, promises.
==============================================================================
CONTENTS
==============================================================================
This directory contains source for the following programming examples:
libstereo.a : contains a set of support routines for programming stereo
--built from onoffstereo.c, stereopersp.c, stereowin.c,
and stereo.h
backg : creates a simple stereo background
grid : draws a simple stereo diagnostic program grid (viewed w/a
closed left eye, a red grid and the word "RIGHT" is
visible, viewed w/a closed right eye, a blue grid and the
word "LEFT" is visible)
on/off -stereo : simple routines for turning on and off stereo mode.
NEW ADDITIONS
nestedcubes : a simple stereo application modified to support
SoftStereo
CheckExtension : An X program to test for the new SGI SoftStereo-in-a-window
implementation available on some platforms under IRIX 5.2.
Run this included (built on 5.1) executable to see if the
required "SoftStereo extension" is found on the machine
you are running on or not.
SGIStereo.o : A 4.0.5 object with XSGI extensions that allows querying
for and using SoftStereo under IRIX 5.2 from 4.0.5
built applications
libXext.a : A sample 5.1 archive with XSGI extansions. This should
NOT be used if you are compiling on IRIX on 5.2
or later since the library in /usr/lib surpasses this
get.h : An example header file with definitions for the two
new SoftStereo modes STR_TOP and STR_BOT. This should
NOT be used if you are compiling on IRIX on 5.2
or later since the header in /usr/include/gl surpasses this
==============================================================================
MAKING THE EXAMPLES
==============================================================================
The Makefile in this example is set to build for IRIX 5.2 by default.
You will need to comment out one line in the Makefile and uncomment
one other for IRIX 4.0.5 makes.
If you are working on 5.2 or later you should use the IRIX versions
of the following, instead of the ones included in this directory:
libXext.a in /usr/lib/libXext.a or libXext.so
SGIStereo.h in /usr/include/X11/extensions/SGIStereo.h
To compile--as 4Dgifts user--type 'make' in this directory. If you
are doing this for the first time, make will first build libstereo.a
from onoffstereo.c, stereopersp.c, stereowin.c, and, stereo.h.
If you want to see: Then execute the command(s):
------------------------ ----------------------------
if stereo works properly grid
a fullscreen application nestedcubes
a windowed application backg; sleep 2; nestedcubes -w
a normal display offstereo
if SOftStereo is supported CheckExtension
-------------------------------------------------------
| You will need IRIX 3.3 or later to run these demos |
| in the old full screen stereo mode |
-------------------------------------------------------
| You will need IRIX 5.2 or later to run the demos |
| which use the new SoftStereo-in-a-window mode on |
| XL - XZ - XS - Elan - Extreme - PI GR1.2 |
-------------------------------------------------------
==============================================================================
MAKING A STEREO APPLICATION
==============================================================================
Here's a short description of what is involved in stereo-izing an application:
1) SET STEREO MODE
Your application must turn on stereo by issuing a
setmonitor(mode) command. You should check to see if
stereo mode is supported by issuing a getgdesc(GD_STEREO)
command. Three stereo modes are possible if SoftStereo
is supported:
STR_RECT - Traditional full screen stereo mode
STR_BOT - New SoftStereo-in-a-window stereo using the bottom
half of the X display
STR_TOP - New SoftStereo-in-a-window stereo using the top
half of the X display
Using the new API your app can inquire if SoftStereo is supported
with:
if(XSGIStereoQueryExtension(XtDisplay(widget), event, error))
sofStereo = TRUE;
Your app can inquire what version of stereo is supported with:
XSGIStereoQueryVersion(XtDisplay(widget), &majorRev, &minorRev);
There are also XSGI extensions available to set some stereo
characteristics controlled by the X server. These are for
applications with special requirements and are not required by
basic stereo applications.
2) CONSTRAIN MOUSE FOR OLD STEREO
Using full screen stereo you should also constrain the mouse to
the lower half of the screen using a setvaluator() command.
In SoftStereo mode the X server will automatically constrain
the mouse for you.
(All three of the above-mentioned calls come from the Graphics
Library (GL)--consult 3G-section (GL Reference Manual) man
pages.) A routine called stereo_on() in libstereo.a does
all of this for you; see the code in onoffstereo.c, and the
comments in stereo.h.
3) WINDOWS
FULL SCREEN STEREO
You must decide if the application should take over the
entire screen, or if it should run in (user-resizeable)
windows. If it takes over the entire screen, you should
set up two viewports (one for each eye) in the upper and
lower halves of the screen. If it should run in a window,
you will have to open two windows, one in the upper and
one in the lower half of the screen. If it runs in
windows, you will also probably want to put up an
appropriate background to cover up all of the regular,
non-stereo windows; see the code in backg for an example.
See the code in nestedcubes for an example application,
and see stereo.h for some simple support routines for
doing stereo in windows.
SOFTSTEREO IN A WINDOW
SoftStereo uses only one window for both eyes. The X server
maintains a STEREO_BUFFER_LEFT and a STEREO_BUFFER_RIGHT
using just one X window. X and Motif windows are automatically
drawn in both buffers so the app doesn't have to deal with this.
The app does need to draw two copies of GL images with or without
the projection change for left and right eyes. You don't
need to obscure any windows in this mode since all windows
will be usable except that their apparent height on the screen
is doubled. If GL windows are not drawn twice they will be
visible to only one eye.
3) A stereo application must draw its scene twice, once for the
left-eye view, and once for the right-eye view. The
'stereopersp' command in libstereo.a can be very useful for
generating correct perspective stereo images. For more
information, see the Summer 1989 issue of the "Iris
Universe," (pp. 16-18, 20-22) which has a very informative
article by Thant Tessman about stereo projections. Again,
see the code in nestedcubes for an example using
stereopersp().
==============================================================================
BUGS
==============================================================================
It has been observed that some or all of these examples may have the
left and right eye views reversed. Due to an impending deadline this
could not be confirmed or denied by testing. Testing with stereo
glasses is the only definitive way to ascertain this since left and
right eye must match the stereo emitter. If this is the case its
relatively easy to swap the images to correct this problem.
There is a known problem using setmon on XZ/Elan/Express graphics
under IRIX 5.1. This problem may result in a graphics hang and/or
Xsgi crash when using setmon. This problem is fixed in IRIX 5.2.
offstereo always returns the display to 60hz mode which may not
be the normal mode, especaillay on Reality Engine.
If you use autoplacement on 4Dwm the nestedcubes window may be placed
out of view.
Source
Documentation
Reference
OR, ...